Skip to main content

7.3 - How to Debug and Analyze Replays

A bot can have flawless code but a flawed strategy. Identifying these strategic bugs requires a different approach than traditional debugging. Your primary tools are controlled local testing, instrumented logging, and most importantly, systematic replay analysis.

The Debugging Workflow​

Effective debugging is a cycle of testing, observation, and refinement.

+--------------------------+
|  1. Run a Local Test     | <-- Control the variables (map, opponent).
|  (Generate Logs & Replay)|
+--------------------------+
           |
           v
+--------------------------+
|  2. Analyze the Replay   | <-- Watch the game from all perspectives.
|  (Cross-reference logs)  |
+--------------------------+
           |
           v
+--------------------------+
|  3. Identify a Flaw      | <-- "My army attacked into a bad position at 5:30."
|  (Form a hypothesis)     |
+--------------------------+
           |
           v
+--------------------------+
|  4. Modify the Code      | <-- "Add a check to retreat if the enemy
|  (Implement a fix)       |      army value is 20% higher."
+--------------------------+
           |
           '---------------------> (Repeat)

1. Local Testing: Your Laboratory​

The run_game block is your testing environment. Use it to create specific, repeatable scenarios.

Test Typerun_game ConfigurationPurpose
Unit Testrealtime=False, no opponent.Quickly test a single mechanic (e.g., "Does my build order complete?").
Integration Testrealtime=True, Computer opponent.Test how your bot's systems work together against a predictable opponent.
Strategy Testrealtime=True, vs. another of your bots.Pit specific strategies against each other to find counters and weaknesses.

Pro Tip: To make your tests repeatable, you can set a random_seed. This ensures that "random" choices (like which worker to select) are the same every time you run the test.

from sc2.main import run_game

run_game(..., random_seed=12345)

2. Instrumented Logging: Your Bot's "Black Box"​

Your logs are the "black box recorder" of your bot's decisions. Good logs explain why an action was taken.

Logging Best PracticeInefficient Log (print("Attacking"))Instrumented Log (Better)
Be Specific & Contextualprint("Building depot")print(f"[{self.time_formatted}] Supply is {self.supply_used}/{self.supply_cap}. Building a depot.")
Log State Changesprint("Fighting")print(f"[{self.time_formatted}] Army value: 1200, Enemy value: 800. Engaging.")
Throttle Your LogsPrinting every step.if self.time - self.last_log_time > 5:

Recommended Library: loguru The burnysc2 library comes with loguru pre-installed. It provides colored, timestamped, and leveled logging with almost no setup, making it a professional replacement for print().

from loguru import logger

# In on_start:
logger.add("logs/my_bot_log.log", rotation="10 MB") # Automatically saves logs to a file.

# In on_step:
if self.supply_left < 5:
    logger.info(f"Supply low ({self.supply_left}), queuing a depot.")

3. Replay Analysis: The Post-Mortem​

A replay is the ultimate ground truth. It shows you exactly what happened, free from your bot's flawed perception.

Replay Analysis Checklist:

  • 1. Save the Replay: 
    from sc2.main import run_game

    run_game(..., save_replay_as="MyBot_vs_Rush.SC2Replay")
  • 2. Open StarCraft II: Launch the game client manually and go to the "Replays" tab.
  • 3. Use Observer Tools Systematically:
    • Watch from Your Bot's Perspective: What did it see? Was its vision limited?
    • Watch from the Enemy's Perspective: How did they react to you? Did they scout your strategy?
    • Watch with Full Vision: See the "perfect information" view. Where could your bot have made a better decision if it had scouted?
  • 4. Cross-Reference with Logs: Have your log file open. If the log says "Engaging enemy at 5:30," jump to that timestamp in the replay. Did the engagement happen as your bot intended?

Key Questions to Ask During Analysis:

  • Economy: Are my workers ever idle? Is my money high while my production is not queued?
  • Strategy: Did I expand at the right time? Did I build the correct counter-units?
  • Tactics: Did my army get caught in a bad position? Did I focus fire the wrong targets?

By treating debugging as a scientific process of forming a hypothesis, running a controlled test, and analyzing the results, you can systematically improve both the code and the strategic intelligence of your bot.